home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / os2trace.zip / OS2TRACE.DOC next >
Text File  |  1997-05-20  |  34KB  |  641 lines
  1.  
  2.  
  3.           Operating System/2 API Trace Enabler/Customizer/Summarizer
  4.  
  5.   Author       : Dave Blaschke
  6.                  IBM Austin, Texas
  7.                  Internal (Notes) - Dave Blaschke@IBMUS
  8.                  Internal (VM)    - IBMUSM26(BLASCHKE)
  9.                  External         - blaschke@us.ibm.com
  10.  
  11.   Description  : Enables or disables  the tracing of 16-bit and 32-bit  OS/2
  12.                  APIs imported by an executable  file  without affecting its
  13.                  source code,  and customizes and summarizes  the tracing of
  14.                  16-bit and 32-bit OS/2 APIs.
  15.  
  16.                  The  first  feat,   trace   enabling  and   disabling,   is
  17.                  accomplished  by  processing  each  entry in  the  table of
  18.                  strings within the executable  file that contains the names
  19.                  of the imported DLLs.  If the entry  represents one  of the
  20.                  supported OS/2  DLLs and the  user requested  enablement of
  21.                  API tracing  for this DLL,  the entry is replaced  with the
  22.                  name  of the  appropriate  trace DLL.  When the  executable
  23.                  file is invoked,  the trace DLL intercepts API calls to its
  24.                  corresponding OS/2 DLL, logs API input information, invokes
  25.                  the API,  and logs  API output  information.  If  the entry
  26.                  represents one  of the  trace DLLs  and the  user requested
  27.                  disablement  of  API  tracing  for this  DLL,  the entry is
  28.                  replaced  with the  name of the  supported OS/2  DLL.  When
  29.                  finished,  the updated table  of strings is  written to the
  30.                  executable file.
  31.  
  32.                  NOTE:   All  private  APIs  are  simply  forwarded  to  the
  33.                  corresponding OS/2 DLL with  no intervention from the trace
  34.                  DLL.
  35.  
  36.                  The  user   can  request   enablement  of  API  tracing  by
  37.                  specifying the -ON option or can request disablement of API
  38.                  tracing  by  specifying  the  -OFF  option.  The  user  can
  39.                  request enablement or disablement of API tracing for one or
  40.                  more of the supported DLLs  individually by specifying each
  41.                  DLL's name  as an  option,  or can  request  enablement  or
  42.                  disablement  of  API  tracing  for all  supported  DLLs  by
  43.                  specifying the -ALL option.
  44.  
  45.                  NOTE:  Trace enablement alters the contents of the table of
  46.                  strings within the executable file  that contains the names
  47.                  of the imported DLLs.  Although this action does not affect
  48.                  the  functionality of  the executable,  it does  affect its
  49.                  date and time stamp.
  50.  
  51.                  The  second feat,  trace customizing,  is  accomplished  by
  52.                  storing the state of the trace customization options in the
  53.                  operating  system's  user profile,  OS2.INI.  The  state of
  54.                  these options can then be  retrieved by the trace DLLs when
  55.                  a trace-enabled executable commences running.
  56.  
  57.                  The user  can request to log a  maximum number of  bytes of
  58.                  level 3  trace information  from buffers by  specifying the
  59.                  -B n  option,  where n is  a decimal number between  16 and
  60.                  65536 (64KB),  inclusive,  and is rounded up to the nearest
  61.                  multiple of 16.  The user  can request  to log all  level 3
  62.                  trace  information  from buffers  by specifying  the -B ALL
  63.                  option.  The user can request to  trace specific groups  of
  64.                  APIs  from  DOSCALLS.DLL  by  specifying  the -D g  option,
  65.                  where g is ALL (request all API groups), one or more of the
  66.                  following delimited  by commas  (request only  specific API
  67.                  groups),  or ALL  and one  or more  of the  following  each
  68.                  prefixed  by a "NO"  and delimited  by commas  (request all
  69.                  except specific API groups):
  70.  
  71.                    DEV  indicates trace device API group
  72.                    FILE indicates trace file API group
  73.                    MEM  indicates trace memory API group
  74.                    MISC indicates trace miscellaneous API group
  75.                    MOD  indicates trace module API group
  76.                    MVDM indicates trace MVDM API group
  77.                    NLS  indicates trace national language support API group
  78.                    PIPE indicates trace pipe API group
  79.                    PRF  indicates trace performance API group
  80.                    PROC indicates trace process and thread API group
  81.                    RES  indicates trace resource API group
  82.                    SEM  indicates trace semaphore API group
  83.                    SES  indicates trace session API group
  84.                    TIME indicates trace date/time and timer API group
  85.                    XCPT indicates trace exception API group
  86.                    MSG  indicates trace message API group
  87.                    INFO indicates trace InfoSeg API group
  88.                    SIG  indicates trace signal API group
  89.  
  90.                  The user can  request to log a  maximum  number of bytes of
  91.                  trace  information  before  log file wrapping  (overwriting
  92.                  from the beginning) occurs by  specifying the  -F n option,
  93.                  where n is a decimal number between 4096 (4KB) and 67108864
  94.                  (64MB),  inclusive,  and  is  rounded  up  to  the  nearest
  95.                  multiple of 4096.  The user  can request  to log  all trace
  96.                  information  without  log file  wrapping by  specifying the
  97.                  -F ALL option.
  98.  
  99.                  NOTE:  -F ALL appends trace  information to the  end of any
  100.                  preexisting trace information file,  while -F n  erases the
  101.                  contents of any preexisting trace information file.
  102.  
  103.                  The user can request to  trace specific groups of APIs from
  104.                  PMGPI.DLL by  specifying  the -G g  option, where  g is ALL
  105.                  (request all  API groups),  one  or more  of the  following
  106.                  delimited by commas (request only specific API groups),  or
  107.                  ALL and one  or more of  the following  each prefixed  by a
  108.                  "NO" and delimited  by commas  (request all except specific
  109.                  API groups):
  110.  
  111.                    BIT  indicates trace bitmap API group
  112.                    CORR indicates trace correlation API group
  113.                    CTRL indicates trace control API group
  114.                    DEF  indicates trace defaults API group
  115.                    EDIT indicates trace segment editing API group
  116.                    LCID indicates trace LCID API group
  117.                    LCT  indicates trace logical color table API group
  118.                    META indicates trace metafile API group
  119.                    PATH indicates trace path API group
  120.                    POLY indicates trace polygon API group
  121.                    PRIM indicates trace primitive API group
  122.                    RGN  indicates trace region API group
  123.                    SEG  indicates trace segment API group
  124.                    TRAN indicates trace transform API group
  125.                    DEV  indicates trace device API group
  126.  
  127.                  The  user  can request  to log  specific  levels  of  trace
  128.                  information by  specifying the -L n option,  where n is one
  129.                  of the following:
  130.  
  131.                    1 indicates log API entry/exit information
  132.                    2 indicates log API parameters
  133.                    3 indicates log API parameter contents
  134.  
  135.                  The user can request to enable time stamping of API entries
  136.                  and exits by  specifying the  -T ON  option.  The user  can
  137.                  request to disable  time stamping of API  entries and exits
  138.                  by specifying the -T OFF option.
  139.  
  140.                  NOTE:  API entry time  stamps reflect  entry into the trace
  141.                  API, not entry into the actual OS/2 API.
  142.  
  143.                  The user can request to  trace specific groups of APIs from
  144.                  PMWIN.DLL by  specifying  the -W g  option, where  g is ALL
  145.                  (request all  API groups),  one  or more  of the  following
  146.                  delimited by commas (request only specific API groups),  or
  147.                  ALL and one  or more of  the following  each prefixed  by a
  148.                  "NO" and delimited  by commas  (request all except specific
  149.                  API groups):
  150.  
  151.                    ACCL indicates trace accelerator API group
  152.                    ATOM indicates trace atom API group
  153.                    CLIP indicates trace clipboard API group
  154.                    CTRY indicates trace country API group
  155.                    CUR  indicates trace cursor API group
  156.                    DDE  indicates trace DDE API group
  157.                    DESK indicates trace desktop API group
  158.                    DLG  indicates trace dialog API group
  159.                    DWIN indicates trace WinDefWindowProc
  160.                    ERR  indicates trace error API group
  161.                    FRAM indicates trace frame API group
  162.                    HOOK indicates trace hook API group
  163.                    INPT indicates trace input API group
  164.                    LOAD indicates trace load API group
  165.                    MENU indicates trace menu API group
  166.                    MSG  indicates trace message API group  (does not include
  167.                         MSGL group)
  168.                    MSGL indicates trace WinDispatchMsg and WinGetMsg
  169.                    PAL  indicates trace palette API group
  170.                    PTR  indicates trace pointer API group
  171.                    RECT indicates trace rectangle API group
  172.                    SYS  indicates trace system API group
  173.                    THK  indicates trace thunk API group
  174.                    TIME indicates trace time API group
  175.                    TREC indicates trace track rectangle API group
  176.                    WIN  indicates trace window API group  (does not  include
  177.                         DWIN group)
  178.  
  179.                  NOTE:  DWIN and MSGL are separated from WIN and MSG because
  180.                  these  APIs,  when being  traced,  can severely  impact the
  181.                  performance of the trace-enabled executable.
  182.  
  183.                  The  third  feat,  trace  summarizing,  is  accomplished by
  184.                  parsing  the   trace  information   file  generated   by  a
  185.                  trace-enabled  executable and  recording the  number of API
  186.                  entries and exits  logged in the file.  When finished,  the
  187.                  summary statistics  are displayed in  alphabetical order to
  188.                  standard output.
  189.  
  190.                  The user  can request to summarize  the contents of a trace
  191.                  information file by specifying the -S option.
  192.  
  193.                  The user can request helping  information by specifying the
  194.                  -?, -H, or -HELP option.
  195.  
  196.   Installation : Place the executables,  OS2TRACE.EXE and PMOS2TRC.EXE, in a
  197.                  directory   along   the  PATH,   place   the   help   file,
  198.                  PMOS2TRC.HLP,  in a  directory  along the  HELP environment
  199.                  variable, and place the trace DLLs, T_*.DLL, in a directory
  200.                  along the LIBPATH.
  201.  
  202.   Usage        : Trace enabler -
  203.  
  204.                  OS2TRACE -OFF|-ON {-ALL|-dll}... file
  205.  
  206.                  Where:
  207.                    -OFF indicates disable API tracing
  208.                    -ON  indicates enable API tracing
  209.                    -ALL indicates enable/disable API tracing for all DLLs
  210.                    -dll indicates  enable/disable  API tracing  for specific
  211.                         DLL, where dll can be one of the following:
  212.                           DOSCALLS  HELPMGR   KBDCALLS  MONCALLS  MOUCALLS
  213.                           MSG       NAMPIPES  NLS       PMCTLS    PMDRAG
  214.                           PMGPI     PMMERGE   PMPIC     PMSHAPI   PMSPL
  215.                           PMWIN     PMWP      QUECALLS  SESMGR
  216.                    file indicates  name  of  executable  file  to  be  trace
  217.                         enabled/disabled
  218.  
  219.                  NOTE:     Trace  enablement  alters  the  contents  of  the
  220.                  executable file's import module name table.
  221.  
  222.                  In  the following example,  tracing is enabled  in TEST.EXE
  223.                  for the APIs imported from QUECALLS and SESMGR:
  224.  
  225.                  OS2TRACE -ON -QUECALLS -SESMGR TEST.EXE
  226.  
  227.                  In  the following example,  tracing is disabled in TEST.EXE
  228.                  for the APIs imported from all supported DLLs:
  229.  
  230.                  OS2TRACE -OFF -ALL TEST.EXE
  231.  
  232.                  Trace customizer -
  233.  
  234.                  OS2TRACE {-B n|-D g|-F n|-G g|-L n|-T f|-W g}...
  235.  
  236.                  Where:
  237.                    -B n indicates log maximum of n bytes from buffers, where
  238.                         16 ≤ n ≤ 65536 or n is ALL to indicate log all bytes
  239.                         from buffers
  240.                    -D g indicates trace specific DOSCALLS API groups,  where
  241.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  242.                         is one of the following:
  243.                           DEV       FILE      MEM       MISC      MOD
  244.                           MVDM      NLS       PIPE      PRF       PROC
  245.                           RES       SEM       SES       TIME      XCPT
  246.                           MSG       INFO      SIG
  247.                    -F n indicates  log maximum  of n  bytes before  log file
  248.                         wrapping occurs,  where 4096 ≤ n ≤ 67108864  or n is
  249.                         ALL to indicate log all information without log file
  250.                         wrapping
  251.                    -G g indicates  trace  specific  PMGPI API groups,  where
  252.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  253.                         is one of the following:
  254.                           BIT       CORR      CTRL      DEF       EDIT
  255.                           LCID      LCT       META      PATH      POLY
  256.                           PRIM      RGN       SEG       TRAN      DEV
  257.                           INK
  258.                    -L n indicates log level n information, where 1 ≤ n ≤ 3:
  259.                           1 indicates log API entry/exit information
  260.                           2 indicates log API parameters
  261.                           3 indicates log API parameter contents
  262.                    -T f indicates enable (f = ON)  or disable (f = OFF) time
  263.                         stamping of API entries and exits
  264.                    -W g indicates  trace  specific  PMWIN API groups,  where
  265.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  266.                         is one of the following:
  267.                           ACCL      ATOM      CLIP      CTRY      CUR
  268.                           DDE       DESK      DLG       ERR       FRAM
  269.                           HOOK      INPT      LOAD      MENU      MSG
  270.                           PAL       PTR       RECT      SYS       THK
  271.                           TIME      TREC      WIN
  272.  
  273.                  NOTE: The default trace customization option settings are:
  274.  
  275.                  -B 256 -D ALL -F ALL -G ALL -L 1 -T OFF -W ALL
  276.  
  277.                  In the  following  example,  tracing is  customized  to log
  278.                  a maximum of  512 bytes of  level 3 trace information  from
  279.                  buffers:
  280.  
  281.                  OS2TRACE -B 512
  282.  
  283.                  In the  following example,  tracing is customized  to trace
  284.                  only memory and semaphore API groups from DOSCALLS.DLL:
  285.  
  286.                  OS2TRACE -D MEM,SEM
  287.  
  288.                  In the  following  example,  tracing is  customized  to log
  289.                  a maximum of 16384  bytes of  trace information  before log
  290.                  file wrapping occurs:
  291.  
  292.                  OS2TRACE -F 16384
  293.  
  294.                  In the  following example,  tracing is customized  to trace
  295.                  only  bitmap,  metafile,  and  transform  API  groups  from
  296.                  PMGPI.DLL:
  297.  
  298.                  OS2TRACE -G BIT,META,TRAN
  299.  
  300.                  In the  following  example,  tracing is  customized  to log
  301.                  level 2 information:
  302.  
  303.                  OS2TRACE -L 2
  304.  
  305.                  In the  following example,  tracing is customized to enable
  306.                  time stamping of API entries/exits:
  307.  
  308.                  OS2TRACE -T ON
  309.  
  310.                  In the  following example,  tracing is customized  to trace
  311.                  all except hook and system API groups from PMWIN.DLL:
  312.  
  313.                  OS2TRACE -W ALL,NOHOOK,NOSYS
  314.  
  315.                  Trace summarizer -
  316.  
  317.                  OS2TRACE -S file
  318.  
  319.                  Where:
  320.                    -S   indicates summarize API tracing
  321.                    file indicates name of trace information file to be trace
  322.                         summarized
  323.  
  324.                  In the following example, tracing in TEST.TRC is summarized
  325.                  and placed in TEST.SUM:
  326.  
  327.                  OS2TRACE -S TEST.TRC > TEST.SUM
  328.  
  329.                  Trace PM interface -
  330.  
  331.                  PMOS2TRC
  332.  
  333.   Scenario     : The following  example shows a  typical scenario  where the
  334.                  three personalities of OS2TRACE  can be used in  conjuction
  335.                  to produce a summary of NLS APIs used by TEST.EXE:
  336.  
  337.                  OS2TRACE -D NLS -L 1
  338.                  OS2TRACE -ON -DOSCALLS -NLS TEST.EXE
  339.                  TEST
  340.                  OS2TRACE -OFF -DOSCALLS -NLS TEST.EXE
  341.                  OS2TRACE -S TEST.TRC > TEST.NLS
  342.  
  343.                  The first  line  customizes  API tracing,  the second  line
  344.                  enables API tracing, the third line invokes the executable,
  345.                  which places  all its API tracing  information in TEST.TRC,
  346.                  the fourth line  disables API tracing,  and the fifth  line
  347.                  summarizes API tracing.
  348.  
  349.                  The above example  can also be performed  completely within
  350.                  the  PM interface.  The following starts the PM interface:
  351.  
  352.                  PMOS2TRC
  353.  
  354.                  The following then enables launching of .EXE files from the
  355.                  PM interface:
  356.  
  357.                  1. Select Options/Launch .EXE files from main window
  358.  
  359.                  The following then sets the logging level to 1  (equivalent
  360.                  to OS2TRACE -L 1):
  361.  
  362.                  2. Select Customize/Logging level... from main window
  363.                  3. Click on Log API entry/exit (level 1) information button
  364.                  4. Click on OK button to dismiss logging level dialog
  365.  
  366.                  The following then sets the DOSCALLS APIs group to NLS only
  367.                  (equivalent to OS2TRACE -D NLS):
  368.  
  369.                  5. Select Customize/DOSCALLS APIs... from main window
  370.                  6. Click on Clear button in DOSCALLS APIs dialog
  371.                  7. Click on NLS button in same dialog
  372.                  8. Click on OK button to dismiss DOSCALLS APIs dialog
  373.  
  374.                  The following then enables tracing of DOSCALLS and NLS DLLs
  375.                  by TEST.EXE (equivalent to OS2TRACE -ON -DOSCALLS -NLS
  376.                  TEST.EXE):
  377.  
  378.                  9. Select Enable/Open file... from main window
  379.                  10. Enter TEST.EXE in entry field of open file dialog
  380.                  11. Click on OK button to dismiss open file dialog
  381.                  12. Click on All Off button in enablement dialog
  382.                  13. Click on DOSCALLS "On" button in same dialog
  383.                  14. Click on NLS "On" button in same dialog
  384.                  15. Click on OK button to dismiss enablement dialog
  385.  
  386.                  At this point a dialog is  presented for launching the .EXE
  387.                  file.  Because TEST.EXE requires no command line parameters
  388.                  and can run in the foreground,  the following then launches
  389.                  TEST.EXE:
  390.  
  391.                  16. Click on OK button to dismiss launch dialog
  392.  
  393.                  After TEST.EXE has completed executing,  the following then
  394.                  disables  tracing of  all DLLs  by TEST.EXE  (equivalent to
  395.                  OS2TRACE -OFF -ALL TEST.EXE):
  396.  
  397.                  17. Select Enable/Open file... from main window
  398.                  18. Enter TEST.EXE in entry field of open file dialog
  399.                  19. Click on OK button to dismiss open file dialog
  400.                  20. Click on All Off button in enablement dialog
  401.                  21. Click on OK button to dismiss enablement dialog
  402.  
  403.                  The  following  then  summarizes   API  tracing  logged  in
  404.                  TEST.TRC and places the results in TEST.NLS  (equivalent to
  405.                  OS2TRACE -S TEST.TRC > TEST.NLS):
  406.  
  407.                  22. Select Summarize/Open file... from main window
  408.                  23. Enter TEST.TRC in entry field of open file dialog
  409.                  24. Click on OK button to dismiss open file dialog
  410.                  25. Click on Save As.. button in summarization dialog
  411.                  26. Enter TEST.NLS in entry field of save file dialog
  412.                  27. Click on OK button to dismiss save file dialog
  413.                  28. Click on OK button to dismiss summarization dialog
  414.  
  415.   Output       : Trace enabler -
  416.  
  417.                  If  the  user  requests  enablement  of  API  tracing  (-ON
  418.                  option),  information similar to the following is displayed
  419.                  for each requested  DLL that is imported  by the executable
  420.                  file:
  421.  
  422.                  DLLNAME : File imports from DLL, API tracing enabled
  423.  
  424.                  information similar to the  following is displayed for each
  425.                  requested DLL  whose trace DLL  is already imported  by the
  426.                  executable file:
  427.  
  428.                  DLLNAME : File imports from trace DLL,  API tracing already
  429.                            enabled
  430.  
  431.                  information similar to the  following is displayed for each
  432.                  requested DLL that is not imported by the executable file:
  433.  
  434.                  DLLNAME : File does not  import from DLL,  API  tracing not
  435.                            enabled
  436.  
  437.                  information similar to the  following is displayed for each
  438.                  requested  DLL  that  has  an  API  name  imported  by  the
  439.                  executable file:
  440.  
  441.                  DLLNAME : File imports APINAME by name,  API tracing cannot
  442.                            be enabled
  443.  
  444.                  and information similar  to the following  is displayed for
  445.                  each requested DLL that has an unsupported ordinal imported
  446.                  by the executable file:
  447.  
  448.                  DLLNAME : File imports  unsupported ordinal N,  API tracing
  449.                            cannot be enabled
  450.  
  451.                  If  the  user  requests disablement  of  API tracing  (-OFF
  452.                  option),  information similar to the following is displayed
  453.                  for  each  requested  trace  DLL that  is imported  by  the
  454.                  executable file:
  455.  
  456.                  DLLNAME : File imports from trace DLL, API tracing disabled
  457.  
  458.                  information similar to the  following is displayed for each
  459.                  requested trace DLL  whose DLL  is already imported  by the
  460.                  executable file:
  461.  
  462.                  DLLNAME : File  imports  from  DLL,   API  tracing  already
  463.                            disabled
  464.  
  465.                  and information  similar to the following  is displayed for
  466.                  each  requested  trace DLL  that is  not  imported  by  the
  467.                  executable file:
  468.  
  469.                  DLLNAME : File does not import from trace DLL,  API tracing
  470.                            not disabled
  471.  
  472.                  Trace customizer -
  473.  
  474.                  If the user requests customization of API tracing  (-B, -D,
  475.                  -F, -G, -L, -T, and/or -W options),  information similar to
  476.                  the following is displayed:
  477.  
  478.                  Old trace customization options: -B 64 -D ALL -F ALL ...
  479.                  New trace customization options: -B 256 -D SEM -F 65536 ...
  480.  
  481.                  The  first   line  contains   the   state   of  the   trace
  482.                  customization  options prior to the invocation of  OS2TRACE
  483.                  while  the  second line  contains the  state of  the  trace
  484.                  customization options after the invocation of OS2TRACE.
  485.  
  486.                  Trace summarizer -
  487.  
  488.                  If the user  requests  summarization  of the  contents of a
  489.                  trace information file (-S option),  information similar to
  490.                  the following is displayed:
  491.  
  492.                  Used APIs:
  493.                    APINAME (4 Pass)
  494.                       :
  495.                    APINAME (12 Pass, 4 Fail, 2 No Return)
  496.  
  497.                  Each line contains the name of the used API,  the number of
  498.                  successful invocations, if any,  the number of unsuccessful
  499.                  invocations, if any,  and the number of API entries without
  500.                  matching  exits  (indicated  by  "No Return"),  if any.  It
  501.                  should be noted that these  APIs are listed in alphabetical
  502.                  order.
  503.  
  504.                  Trace-enabled executable -
  505.  
  506.                  All  levels of  information,  from the  trace-enabled  .EXE
  507.                  and/or any  trace-enabled  .DLLs that  are attached  to the
  508.                  .EXE,  are logged  to a text  file  with a  file name  that
  509.                  matches the  .EXE file name and an extension of .TRC.  This
  510.                  trace information  file  resides in the  same directory  as
  511.                  the  .EXE file.  If another  instance of the  same .EXE  is
  512.                  already running,  the file name of the text file is changed
  513.                  to PROC  followed  by the  hexadecimal  process  identifier
  514.                  (i.e. PROC003A.TRC).  If this occurs,  a warning message is
  515.                  issued.
  516.  
  517.                  NOTE:  If a REXX program loads any trace-enabled .DLLs, all
  518.                  trace  information  is  logged  to   CMD.TRC  in  the  same
  519.                  directory  as the  CMD.EXE executable  that loaded the REXX
  520.                  program.
  521.  
  522.                  If the user requests  level 1 information,  data similar to
  523.                  the following is logged for each API call:
  524.  
  525.                  003A 0001 | Dos32CreateQueue Entry
  526.  
  527.                  003A 0001 | Dos32CreateQueue Exit
  528.                       PASS | Return code: 0
  529.  
  530.                  If the user requests  level 2 information,  data similar to
  531.                  the following is logged for each API call:
  532.  
  533.                  003A 0001 | Dos32CreateQueue Entry
  534.                            | Parameter 1: PHQUEUE = 0x00028BE8
  535.                            | Parameter 2: ULONG = 0x00000002
  536.                            | Parameter 3: PSZ = 0x000200A4
  537.  
  538.                  003A 0001 | Dos32CreateQueue Exit
  539.                       PASS | Return code: 0
  540.                            | Parameter 1: PHQUEUE = 0x00028BE8
  541.  
  542.                  If the user requests  level 3 information,  data similar to
  543.                  to the following is logged for each API call:
  544.  
  545.                  003A 0001 | Dos32CreateQueue Entry, Return Address =...
  546.                            | Parameter 1: PHQUEUE = 0x00028BE8
  547.                            | Parameter 2: ULONG = 0x00000002
  548.                            | Parameter 3: PSZ = 0x000200A4 ["\QUEUES\..."]
  549.  
  550.                  003A 0001 | Dos32CreateQueue Exit
  551.                       PASS | Return code: 0 (NO_ERROR)
  552.                            | Parameter 1: PHQUEUE = 0x00028BE8 [0x00000007]
  553.  
  554.                  The first number  on both  the API entry  and exit lines is
  555.                  the hexadecimal process identifier (PID) of the executable.
  556.                  The  second  number is the  hexadecimal  thread  identifier
  557.                  (TID) of  the thread within the executable that invoked the
  558.                  API.
  559.  
  560.                  If the user requests  level 3 information  and a character,
  561.                  ASCIIZ string,  integer,  color,  FIXED,  POINTL,  or RECTL
  562.                  buffer is  larger than  the maximum  specified by  the -B n
  563.                  option, the data is truncated and -- More -- is logged.
  564.  
  565.                  If log  file wrapping  occurs,  information similar  to the
  566.                  following is  logged after the executable's  stopping time,
  567.                  OS2TRACE banner, and executable's starting time:
  568.  
  569.                  < Trace information lost due to log file wrapping 3 times >
  570.  
  571.                  All  warning   and  error   messages   generated   by   the
  572.                  trace-enabled  executable  are placed in the  error message
  573.                  file OS2TRACE.ERR  in the  root  directory of the operating
  574.                  system's  boot drive in order  to avoid conflicts  with the
  575.                  executable's output.
  576.  
  577.   History      : Version Date    Item
  578.                  2.30.00 12Jun95 Created (supported LX format and 32-bit Dos
  579.                                  APIs only)
  580.                  2.30.01 09Jul95 Issued warning if trace DLL not on LIBPATH
  581.                  2.30.02 18Jul95 Added optional "NO" prefix to API groups
  582.                  2.30.03 20Jul95 Added 32-bit Win APIs
  583.                  2.30.04 28Jul95 Fixed integer buffer logging
  584.                  2.30.05 04Aug95 Added 32-bit Gpi APIs
  585.                  2.30.06 09Aug95 Fixed Dos32DevIOCtl bug
  586.                  2.30.07 11Aug95 Changed to new build structure
  587.                  2.30.08 11Aug95 Added 32-bit Ddf APIs
  588.                  2.30.09 12Aug95 Added 32-bit Dev APIs
  589.                  2.30.10 13Aug95 Added 32-bit Drg APIs
  590.                  2.30.11 14Aug95 Added 32-bit Prf APIs
  591.                  2.30.12 25Aug95 Fixed Dos32QueryMessageCP bug
  592.                  2.30.13 27Aug95 Added OS/2 for PowerPC support
  593.                  2.30.14 29Aug95 Added 32-bit Prt and Spl APIs
  594.                  2.30.15 29Aug95 Added 32-bit Pic APIs
  595.                  2.30.16 22Sep95 Enhanced -B option
  596.                  2.30.17 22Sep95 Added -F option
  597.                  2.30.18 24Sep95 Added -T option
  598.                  2.30.19 02Nov95 Fixed Drg32DragFiles bug
  599.                  2.30.20 27Nov95 Added support for  Dos APIs  in  MSG,  NLS,
  600.                                  QUECALLS, and SESMGR exported by DOSCALL1
  601.                  2.30.21 13Dec95 Forwarded private entry table ordinals
  602.                  2.30.22 19Dec95 Added new 32-bit OS/2 3.00 non-Uni Dos APIs
  603.                  2.30.23 27Mar96 Fixed PMWIN bugs
  604.                  2.30.24 29Mar96 Added PM interface (supported customization
  605.                                  and help only)
  606.                  2.30.25 15Apr96 Verified DOS header new header file address
  607.                  2.30.26 23May96 Issued more specific enablement messages
  608.                  2.30.27 13Jun96 Logged FEA2 structure EA value
  609.                  2.30.28 14Jun96 Changed "\r\n" to "\n" in output
  610.                  2.30.29 21Jun96 Fixed Dos32UnwindException bug
  611.                  2.30.30 26Jun94 Added 32-bit OS/2 2.00 PM debugger APIs
  612.                  2.40.00 05Sep96 Added new 32-bit OS/2 2.40 APIs
  613.                  2.40.01 27Sep96 Fixed customization information display bug
  614.                  2.40.02 11Mar97 Removed loading/unloading trace DLLs
  615.                  2.40.03 11Mar97 Converted to IBM VisualAge C++
  616.                  2.40.04 12Mar97 Fixed OS/2 for PowerPC DLL support
  617.                  2.40.05 12Mar97 Added enablement support to PM interface
  618.                  2.40.06 12Mar97 Fixed Win32EnumObjectClasses bug
  619.                  2.40.07 13Mar97 Added customization cancel confirmation
  620.                  2.40.08 13Mar97 Added summarization support to PM interface
  621.                  2.40.09 14Mar97 Removed  summarization   API  exit  without
  622.                                  entry error
  623.                  2.40.10 14Mar97 Fixed Dev32StdOpen bug
  624.                  2.40.11 19Mar97 Added  save  window  position  option to PM
  625.                                  interface
  626.                  2.40.12 19Mar97 Added support for NE format
  627.                  2.40.13 20Mar97 Added  launch   .EXE  files  option  to  PM
  628.                                  interface
  629.                  2.40.14 25Mar97 Fixed DENA2 buffer logging
  630.                  2.40.15 01Apr97 Fixed Dos32FindFirst bug
  631.                  2.40.16 15Apr97 Removed OS/2 for PowerPC from PM help
  632.                  2.40.17 21Apr97 Added 16-bit Dos APIs
  633.                  2.40.18 30Apr97 Added 16-bit Kbd APIs
  634.                  2.40.19 01May97 Added 16-bit Mou APIs
  635.                  2.40.20 05May97 Added 16-bit Vio APIs
  636.                  2.40.21 20May97 Fixed/minimized 16-bit stack usage
  637.  
  638.   Please direct all comments,  problems,  questions,  and suggestions to the
  639.   author above.
  640.  
  641.